Address Match API

This document outlines the details of the Address Match API.

API Description

Objective

The Address Match API compares two input addresses and returns an overall similarity score. It also provides segment-level comparison scores for individual address components such as house, street, locality, city, state, and pincode, enabling a detailed evaluation of address similarity.

Input	Output
The two addresses for comparison	Overall similarity score along with individual scores for each address component

API URL

https://ind-engine.thomas.hyperverge.co/v1/address_match

API Endpoint

address_match

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and ﬁles as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Type	Description	Valid Values
`content-type`	Mandatory	string	This parameter defines the media type for the request payload.	multipart/form-data
`appId`	Mandatory	string	The application ID shared by HyperVerge	Not Applicable - this is a unique value.
`appKey`	Mandatory	string	The application key shared by HyperVerge	Not Applicable - this is a unique value.
`transactionId`	Mandatory	string	The unique ID for the customer journey.	Not Applicable - this is a unique value related to a transaction in your application.

Input

The following table provides the details of the parameter required for the API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
`address1`	Mandatory	The first address. This value will be compared with the `address2` parameter	A valid address string	Not Applicable
`address2`	Mandatory	The second address. This value will be compared with the `address1` parameter	A valid address string	Not Applicable
`returnMatchingSegments`	Optional	Indicates if the response should return the matching address segments	`yes`, `no`	Not Applicable
`region`	Optional	The region for comparison logic, e.g., "ind" for India	Not Applicable	Not Applicable
`returnSegmentScores`	Optional	Indicates if the response should return segment-level scores	`yes`, `no`	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/address_match' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'address1="<Enter_the_first_address>"' \
--form 'address2="<Enter_the_second_address>"' \
--form 'returnMatchingSegments="<Enter_yes_or_no>"' \
--form 'region="<Enter_the_region>"' \
--form 'returnSegmentScores="<Enter_yes_or_no>"'

Success Responses

The following code snippet demonstrates the success responses from the API, when the parameters returnSegmentScores and returnMatchingSegments are enabled in the request:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "overall_score": 0.5,
        "segments": {
            "house": {
                "match": "no",
                "score": 0
            },
            "street_name_or_landmark_nearby": {
                "match": "no",
                "score": 0.55
            },
            "locality": {
                "match": "no",
                "score": 0.35
            },
            "city": {
                "match": "yes",
                "score": 1
            },
            "state": {
                "match": "yes",
                "score": 1
            },
            "pincode": {
                "match": "no",
                "score": 0
            }
        }
    }
}

The following success responses are returned when the parameters returnSegmentScores and returnMatchingSegments are not enabled in the request:

returnSegmentScores not enabled
returnMatchingSegments not enabled

When the returnSegmentScores parameter is not included, only the match results (without scores) for each segment are returned:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "overall_score": 0.51,
        "segments": {
            "house": {
                "match": "no"
            },
            "street_name_or_landmark_nearby": {
                "match": "no"
            },
            "locality": {
                "match": "no"
            },
            "city": {
                "match": "yes"
            },
            "state": {
                "match": "yes"
            },
            "pincode": {
                "match": "no"
            }
        }
    }
}

When the returnMatchingSegments parameter is set to "no" or not included, the response only returns the overall similarity score without any segment-level information:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "overall_score": 0.5
    }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code for the request
result	object	The result object containing the address match details
overall_score	float	The overall score representing the similarity between the two addresses, ranging from 0 to 1
segments	object	An object containing segment-level match results
house	object	The matching result and score (if applicable) for the house number or building
house.match	string	Indicates if the house information matches between the two addresses
house.score	float	The similarity score for the house segment, ranging from 0 to 1
street_name_or_landmark_nearby	object	The matching result and score (if applicable) for the street name or nearby landmark
street_name_or_landmark_nearby.match	string	Indicates if the street or landmark matches between the two addresses
street_name_or_landmark_nearby.score	float	The similarity score for the street or landmark segment (if returned)
locality	object	The matching result and score (if applicable) for the locality or area
locality.match	string	Indicates if the locality matches between the two addresses
locality.score	float	The similarity score for the locality segment (if returned)
city	object	The matching result and score (if applicable) for the city
city.match	string	Indicates if the city matches between the two addresses
city.score	float	The similarity score for the city segment (if returned)
state	object	The matching result and score (if applicable) for the state
state.match	string	Indicates if the state matches between the two addresses
state.score	float	The similarity score for the state segment (if returned)
pincode	object	The matching result and score (if applicable) for the pincode
pincode.match	string	Indicates if the pincode matches between the two addresses
pincode.score	float	The similarity score for the pincode segment (if returned)

Error Responses

The following are some error responses from the API:

Invalid Request Parameters
Missing/Invalid Credentials
Internal Server Error

{
    "message": "Input Validation Error: requires property \"address1\"",
    "statusCode": 400,
    "status": "failure"
}

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

{
  "status": "failure",
  "statusCode": 500,
  "message": "internal server error"
}

Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message.

The following table lists all error responses:

Status Code	Error Message	Error Description
400	Input Validation Error: requires property `address1`	The address input fields in the request are either missing or invalid
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details

Method - POST